BBS in a Box 5

home *** CD-ROM | disk | FTP | other *** search

/ BBS in a Box 5 / BBS in a Box -Volume V (BBS in a Box) (April 1992).iso / Files / Tele / S / Slic.cpt / SLIC V1.0 / SLIC V1.0

Wrap

Text File | 1991-04-09 | 30.3 KB | 944 lines | [APPL/SLIC]

Survey Language Instruction Converter Version 1.0 By: Char-lez Braden INTRODUCTION The purpose of SLIC is to aid Second Sight (C) users in the creation and editing of Survey files. This comes from my own frustration with using survey files. SLIC is not to be a full featured development environment. Think of it as a custom body shop, not an auto factory. SLIC is MUCH easier to use than native Survey commands, and SLIC can accommodate all the survey commands at the time of it's creation. SLIC cannot contend with every possiblity a user can type in. I've worked hard to make it reject bogus commands, but confusing SLIC is possible. This program is made for those who are willing to try and get it right. I subscribe to the theory of Garbage In, Garbage Out. THIS MANUAL: The manual is divided into four chapters. The first is "Theory of operation". This chapter will cover how you use a survey file and what its capabilities are. The second chapter, "Syntax", gives definitions of each command. The third chapter, "Operation of SLIC.", and tells how to use the program. The fourth chapter is "Tables" and it contains the quick reference material. Slic is marketed under the shareware concept. I'm asking for $15.00, cash, check or charge (Visa or Mastercard). Register your copy for upgrades and support. Call me at 408/942-5480. You may distribute SLIC freely, but you must enclude this documentation file. CHAPTER 1:THEORY OF OPERATION The purpose of this chapter is to give an overview of how a survey file works and what it can do for you. A survey file is very flexible, and I think it would place limits on your imagination to try and say that a survey file is limited to applications A, B and C. The best way to determine what a survey file is good for is to look at what it can and CANNOT do. A survey file can collect data from a user. A survey file can react to the data it collects. A survey file can store the collected data. A survey file can change user time, level & flags. A survey file can build report files. A Survey file can maintain a tally. A Survey file can display a tally. A survey, which collects votes, can be set up to insure that each ID votes only once. A Survey file CANNOT react to user time, level or flags. A Survey file CANNOT read files. If you think a survey is what you need, look at the above list and ask yourself, "Given these abilities, can it do what I need?" I think you will find that even if the answer is no, a combination of surveys and menus will do most any job. First you need to know what a survey file is. A survey file is a set of instructions the computer follows. So, in reality, you program, or script, a survey file. The next thing I want to introduce is the concept of "User Input". User input is what the user sends to you. SLIC represents user input by the keyword "INPUT". You can only deal with one input at a time. Each time you request a new input from the user the old one is erased, so finish what you start! The Response File, call the .RES file, is what you need to know about next. The Response File contains all the final formatted responses from the user. You do not add information directly to the Response File. You format the user input using the Scratch File, described below. Once you have the correct format you append the Scratch File to the Response File. The Scratch File comes next. The scratch file is a temporary file. You use it to format the users input into your desired format. Once the file is formatted you append the scratch file onto the response file. You cannot add anything directly to the response file, all input must first go into the scratch file. The scratch file is erased each time the survey is executed (or when you direct SLIC to erase the file specifically.) To demonstrate these concepts, I have produced a quick demo survey file. DEMO 1: Questionnaire Scenario: You, as the Sys. Op., have determined that you want to validate each user data before giving them access to your system. First you determine which questions are relevant. For this demo we are going to ask for the users real name, phone number and address, but we are in no way limited to these questions. Sample Code: "START" 'Introduction print "Thanks for interest in The Simple BBS." Print Print "Before I give you full access I need some" Print "Personal information." print 'Question #1 input "Real Name :" 35 scratch write input print 'Question #2 input "Phone number ###/###-####:" 12 scratch write input print 'Question #3 input "Address :" 60 Scratch write input print 'Verify input "Is the above correct ?"YN if input = "Y" goto "END" restart "END" 'Save data Scratch append Exit If you want, use your word processor to copy the above code and TRY IT! With just the simple tools from the sample above, you can do plenty, but let's not stop there. The next concept is an accumulator. An accumulator is like the memory on your calculator. You can store a number in it, add numbers to it, subtract numbers from it, or clear it to zero and even print it's values out. You can have as many accumulators as you wish, limited only by the size of your disk. The counter file is a permanent record of accumulators that's written to the disk. That's it! Pretty simple eh? Ok, here's the catch; Like the response file, you don't manipulate the count (.CNT) file directly. The last concept is the special scratch file. The special scratch file is a temporary list of accumulators used to set up accumulators and then add those accumulators to the permanent .CNT file. Why do this? If during the survey you want to undo changes you can just start over, rather than taking into account the original values that were present before you started changing things. In summary, the Special scratch file is to the .CNT file as the Scratch file is to the .RES file. To demonstrate the accumulator concept, I will show you some sample code for a survey that asks to select a users favorite car from a list, and then prints the results. "START" 'See if user has voted before If Registered goto "Voted Before" 'set up special scratch file with 4 accumulators Special init 4 'Introduction "Intro" print "Favorite car survey." print print "1. New Ford Mustang" print "2. Old Ford Mustang" print "3. Other Piece of junk" print input "Which ?"1 if input = "1" goto "New Ford" if input = "2" goto "Old Ford" if input = "3" goto "Junk" "Bad Input" print print "That's not on the list!" print print goto "Intro" "New Ford" A1 +1 goto "Tally" "Old Ford" A2 +1 goto "Tally" "Junk" A3+1 "Tally" a4 =1 'Add results to totals CNT Update "Print Results" print print "Results so far." print print "Total voters so far :"; print C4 print print "New Fords :"; print C1 print "Old Fords :"; print C2 print "Junk :"; print C3 print input "Press return to go to main menu :" return exit "Voted Before" print print "You've already voted." print goto "Print Results" Again, whip out the word processor and try it! CHAPTER 2: SYNTAX SYNTAX: Each instruction follows a RIGID syntax. Nothing is assumed, and nothing can be omitted. When using instructions, the Capitolization letters and correct punctuation are essential. The lower case n denotes a number. When quotes are present, inside will be [text], [name] or [path] to tell you what kind of data is expected. It is important to note that two quotes that follow each other with nothing between them (empty quotes) will generate an error. In cases where the quoted data is optional, it will be noted specifically. The use of quotes with SLIC is both required and tricky. While you can use quotes inside of quotes, SLIC will return some strange capitalization. This is due to the fact that SLIC capitalizes everything before it looks for it's key words. But SLIC also tries to preserve your capitalization. Sometimes conflicts occur, and your text capitalization will be lost. When this happens, take your favorite text editor and retype those lines that were changed. I think you'll find this a minor annoyance at worst. While it seems like this may be restrictive, compare it to what you find in the Second Sight (C) manual and you'll be ecstatic. The commands of SLIC are designed to be as intuitive as possible. Think of this relationship, SLIC is to survey files, as BASIC is to assembler. SLIC takes instructions that you type (easy for humans to understand) and turns them into survey commands (easy for computers to understand). Because the process of writting a survey file with SLIC is one of conversion, I will refer to SLIC commands as instructions, and survey file commands as commands. Special Scratch File Accumulators: Are always referred to as "An". Counter File Accumulators: Are always referred to as "Cn". Literals: n - Numeric "[text]" - Text literal "[path]" - path to a menu or file in the disk "[name]" - name of an instruction to branch to <CR> - Return or Enter characters, ASCII 13 '[comment] Command -1* This instruction is used to document your code. It is actually included in the final survey file, should you ever go looking through it. I strongly suggest you use it too much as opposed to too little. "[label]" Command -2* This instruction is used to name the starting points of routines in your survey. Each section should have a label. It's not critical that everything be labelled, but all the instructions that branch to other instructions must branch to a label. An = n Command 40 This instruction is used to assign a value to a special scratch file accumulator. An + n Command 31 This instruction adds the value of n to the specified special scratch file accumulator. This number n may be a negative number, thus it's effectively a subtraction command also. An1+ An2 Command 32 This instruction adds the second special scratch file accumulator to the first and stores the result in the first special scratch file accumulator. CNT UPDATE Command 37 This instruction adds all of the Special Scratch File Accumulators to their respective .CNT file accumulators. DISPLAY "[path]" C Command 26 DISPLAY "[path]" + Command 27 DISPLAY "[path]" C+ Command 28 DISPLAY "[path]" F Command 29 These instructions are used to display a text file. The parameters at the end specify how the display will be shown. C : Cancellable with Ctrl-C + : Prompts F : Final Prompt only EXIT Command 7 This instruction is used to exit the survey and go return to the active menu. This will usually be the menu that called the survey, but not always. See "Use Menu" below. GOTO "[name]" Command 2 This instruction causes the flow of execution to jump to the line named with the lable instruction (See Above). IF INPUT = NULL GOTO "[name]" Command 4 IF INPUT = "[text]" GOTO "[name]" Command 3 IF REGISTERED GOTO "[name]" Command 39 IF RATIO NOT n:1 GOTO "[name]" Command 21 This instruction has the basic structure of IF (expression) GOTO "[name]". If the expression evaluates as true, then branch to the instruction named. Expressions can be as shown below. INPUT = NULL: The last input a user typed was a <CR> only. INPUT = "[text]": The last input EQUALS what's in text. REGISTERED: The user has already registered his/her vote. RATIO NOT n:1: The users download:upload ratio is not n:1. INPUT "[text]" n Command 9 INPUT "[text]" YN Command 10 INPUT "[text]" RETURN Command 11 INPUT n Command 9 INPUT YN Command 10 INPUT RETURN Command 11 The input instruction has two parameters, text and type. Text is what the users sees before the computer actually expects a response. Usually the text would be the actual question or a prompt of some kind. If you wish to have empty quotes, just leave off the quotes all together. The type parameter tells the computer which kind of input to expect and accept. The three types of input are: n : Allow n Characters YN : Wait for a Y,y or N,n (<CR> counts as "Y") RETURN : wait for <CR> only. PRINT Command 1 PRINT "[text]" Command 1 PRINT "[text]"; Command 1 PRINT An Command 33 PRINT An; Command 35 PRINT Cn Command 34 PRINT Cn; Command 36 PRINT % Cn1/Cn2 Command 41 PRINT % Cn1/Cn2; Command 42 Print has two parameters. The first parameter is the type of information that will be sent to the caller, types are explained below. The second parameter is the semicolon at the end. If a print instruction has a semicolon then no <CR> will be sent, if it does not have a semicolon then a <CR> will be sent. The type parameters are: "Literal" - sends text between quotes An - Sends value of special scratch file accumulator n Cn - Sends value of .CNT file accumulator n % - Sends the percentage of Cn1 to Cn2. Calculated by (Cn1/Cn2)*100. The "%" mark is not sent, you must send it yourself. REGISTER Command 38 The register instruction places the users name in the voted list. This allows you to check who has and hasn't voted, so you can allow or disallow more than one vote per user. RESTART Command 8 RESTART AT "[name]" Command 20 The restart instruction first clears out the Special Scratch File Accumulators by setting them to zero, and then branches to the name given. If no name is given it starts at the beginning of the survey again. SCRATCH APPEND Command 6 SCRATCH SHORT APPEND Command 44 SCRATCH CHAR n Command 19 SCRATCH EOF Command 45 SCRATCH ID Command 46 SCRATCH WRITE "[text]" Command 12 SCRATCH WRITE "[text]"; Command 13 SCRATCH WRITE INPUT Command 5 SCRATCH WRITE INPUT; Command 43 Scratch instructions are really many instructions that I opted to group together for simplicity's sake. Each one deserves its own definition. Scratch Append : This will take what's in the Scratch File and append it to the end of the .RES file. It then appends the EOF ("Above entries made by :[user]/[date]") Scratch Short Append : This appends the Scratch File to the .RES file, but does not append the EOF data. Scratch Char n : This writes the ASCII equivalent of n (0-255) to the Scratch File. Scratch EOF : This writes the EOF to the Scratch File. Scratch ID : This writes [User]/[Date] to the Scratch File. Scratch Write : These four instructions send information to the Scratch File. "[text]" denotes a literal. INPUT means to send the users last input to the Scratch file. If the instruction ends with a semi-colon, then no <CR> will be written to the Scratch File. SET TIME n Command 15 SET LEVEL n Command 17 SET ON n Command 23 SET OFF n Command 25 The Set instructions are used to permanently set the user aspects. Time : in minutes, 0-255. Level : 0-255. On/Off : Denotes user Flags 1-24. SPECIAL INIT n Command 30 The Special Init instruction is used to create the Special Scratch File where n determines the number of accumulators to be used. It sets all the accumulators to zero. Don't use this more than once in a given survey. TEMP TIME n Command 14 TEMP LEVEL n Command 16 TEMP ON n Command 22 TEMP OFF n Command 24 Temp instructions set the various user aspects for the duration of this call only. Time : in minutes, 0-255. Level : 0-255. On/Off : Denotes user Flags 1-24. USE MENU"[path]" Command 18 This instruction is used to set the active menu. You must supply the exact path way on the disc to the menu. If you supply a wrong path Second Sight (C) will default back to the main menu. * instructions -1 & -2 are not true survey file commands. Every command in a survey file has a place for a comment and a name. SLIC always tries to attach a comment or name to the next "real" command, but when more than one comment or label is grouped together then SLIC will use a special case of the command 1 that has no effect. By utilizing the command 1 as a "No Operation" command SLIC can retain all your comments and labels in the actual code. In the purest sense comments will slow execution of a survey file. Chances are that unless you have written an extremely large number of comments, you will see no difference in execution. Please be make liberal use of these commands. CHAPTER 3: Operation of SLIC. SLIC is a converter only, it does not have any text editing features. SLIC version 1.0 has two menu options. Convert: When you select this from the file menu, a finder load dialog box comes up. Use the finder box to locate the file that your word processor created with the commands of your survey. This file is called the source file. Next you will see a finder save dialog box. This asks you for the name of the output file, called the object file. SLIC automatically adds ".OUT" to the name of the in file to prevent accidentally overwriting the source file. Once you have selected both files SLIC immediately begins processing the source file and writing the results to the object file. If SLIC runs into an error it will print the error and the information in the window and stop. After you correct the error you must reconvert the source file. Quit: Select this to exit SLIC. CHAPTER 4: Tables Table 1. instructions to command. An = n Command 40 An + n Command 31 An1+ An2 Command 32 CNT UPDATE Command 37 DISPLAY "[path]" C Command 26 DISPLAY "[path]" + Command 27 DISPLAY "[path]" C+ Command 28 DISPLAY "[path]" F Command 29 EXIT Command 7 GOTO "[name]" Command 2 IF INPUT = NULL GOTO "[name]" Command 4 IF INPUT = "[text]" GOTO "[name]" Command 3 IF REGISTERED GOTO "[name]" Command 39 IF RATIO NOT n:1 GOTO "[name]" Command 21 INPUT "[text]" n Command 9 INPUT "[text]" YN Command 10 INPUT "[text]" RETURN Command 11 INPUT n Command 9 INPUT YN Command 10 INPUT RETURN Command 11 PRINT Command 1 PRINT "[text]" Command 1 PRINT "[text]"; Command 1 PRINT An Command 33 PRINT An; Command 35 PRINT Cn Command 34 PRINT Cn; Command 36 PRINT % Cn1/Cn2 Command 41 PRINT % Cn1/Cn2; Command 42 REGISTER Command 38 RESTART Command 8 RESTART AT "[name]" Command 20 SCRATCH APPEND Command 6 SCRATCH SHORT APPEND Command 44 SCRATCH CHAR n Command 19 SCRATCH EOF Command 45 SCRATCH ID Command 46 SCRATCH WRITE "[text]" Command 12 SCRATCH WRITE "[text]"; Command 13 SCRATCH WRITE INPUT Command 5 SCRATCH WRITE INPUT; Command 43 SET TIME n Command 15 SET LEVEL n Command 17 SET ON n Command 23 SET OFF n Command 25 SPECIAL INIT Command 30 TEMP TIME n Command 14 TEMP LEVEL n Command 16 TEMP ON n Command 22 TEMP OFF n Command 24 USE MENU "[path]" Command 18 TABLE 2. Command to instruction. PRINT Command 1 PRINT "[text]" Command 1 PRINT "[text]"; Command 1 GOTO "[name]" Command 2 IF INPUT = "[text]" GOTO "[name]" Command 3 IF INPUT = NULL GOTO "[name]" Command 4 SCRATCH WRITE INPUT Command 5 SCRATCH APPEND Command 6 EXIT Command 7 RESTART Command 8 INPUT "[text]" n Command 9 INPUT n Command 9 INPUT "[text]" YN Command 10 INPUT YN Command 10 INPUT "[text]" RETURN Command 11 INPUT RETURN Command 11 SCRATCH WRITE "[text]" Command 12 SCRATCH WRITE "[text]"; Command 13 TEMP TIME n Command 14 SET TIME n Command 15 TEMP LEVEL n Command 16 SET LEVEL n Command 17 USE MENU "[path]" Command 18 SCRATCH CHAR n Command 19 RESTART AT "[name] Command 20 IF RATIO NOT n:1 GOTO "[name]" Command 21 TEMP ON n Command 22 SET ON n Command 23 TEMP OFF n Command 24 SET OFF n Command 25 DISPLAY "[path]" C Command 26 DISPLAY "[path]" + Command 27 DISPLAY "[path]" C+ Command 28 DISPLAY "[path]" F Command 29 SPECIAL INIT Command 30 An + n Command 31 An1+ An2 Command 32 PRINT An Command 33 PRINT Cn Command 34 PRINT An; Command 35 PRINT Cn; Command 36 CNT UPDATE Command 37 REGISTER Command 38 IF REGISTERED GOTO "[name]" Command 39 An = n Command 40 PRINT % Cn1/Cn2 Command 41 PRINT % Cn1/Cn2; Command 42 SCRATCH WRITE INPUT; Command 43 SCRATCH SHORT APPEND Command 44 SCRATCH EOF Command 45 SCRATCH ID Command 46 I have worked hard to make sure that SLIC issues useful error messages, not just "This is wrong." But, I have also included an exhaustive list of the error messages from SLIC. I hope these help you if you get into a jam. I have not had this problem, but if you look at a command and it >LOOKS< ok, but you keep getting an error, retype it. Hidden characters will cause problems! 0 = "None" No error has been detected, every thing seems fine. 1 = "Command Too Small to be Valid" The command didn't even have enough characters to be a valid command so SLIC didn't even try and understand it. Minimum number of characters for a valid command is 4. I.E. A1+1, A1=1, EXIT. 2 = "No Equal or Plus in Assignment" SLIC didn't find an "=" or "+" in line that started with an "A", but was not an "ACCEPT" command. The "=" or "+" tells SLIC which kind of assignment to expect. 3 = "Undefined Accumulator in Assignment" SLIC found the "A" and a "+" or "=", but one or both of the accumulator numbers was missing. 4 = "Bad Assignment" Assignment has pieces missing, or extra stuff. For some reason SLIC could not understand it. 5 = "Bad Number" On of the Assignment numbers contained characters that made it an illegal number. 6 = "Unknown Command" One of the lines in the source file started with an unknown command. Check labels to make sure thay have quotes (") and comments to be sure they start with an apostrophie (') 7 = "No Menu" The use menu command was missing the menu to be used. 8 = "Bad Exit Command" The Exit command had extra characters after it. 9 = "Unended Print" This print has a blank double quotes (""). 10 = "Unfinished Goto" This goto did not have a command name or it was unfinished. 11 = "Bad Name" The goto name was unquoted. 12 = "Bad Input" SLIC could tell this was an input command, but unsure as to which one. 13 = "Input command is missing parameter(s)" This input command is missing one of the vital pieces. It could be a Quote or one of the paramters (n, YN, RETURN). 14 = "Input needs a second quote" This input was missing the trailing Quote. 15 = "Unknown Temp command" SLIC thinks this command should be a temp command, but doesn't know which one. 16 = "No Temp Time" The number of minutes is missing. 17 = "No Temp Level" The level number is missing. 18 = "No Temp Flag" The flag number is missing. 19 = "Bad Temp Time" The time you supplied not a valid number, one of the characters is not a number. 20 = "Temp Level Out of Range" The level you supplied was not in the range of 0 to 255. 21 = "Temp Flag Out of Range" The flag number was not in the range of 1 to 24 22 = "Unfinished Display" Missing path and parameters. 23 = "Unknown Parameter" Display command had unknown parameters in it. 24 = "Bad Path" Display command is missing 1st Quote in path. 25 = "Empthy Path" Display path is two quotes with no other characters. 26 = "Unfinshed Path" Display path is missing final Quote. 27 = "Unknown Scratch" SLIC believes this to be a scratch file command, but doesn't know which one. 28 = "Bad Scratch Write" SLIC thinks this command was a Scratch Write, but it's missing parameters or quotes. 29 = "Bad Scratch Text" Scratch text was two quotes side by side. 30 = "Bad Restart" This command was a restart with extra characters that was not a restart at command. 31 = "No Scratch Name" Unused error code. If you get this let me know! 32 = "Bad Restart Name" Restart name was missing one or both quotes. 33 = "Bad Convert" Convert command had extra characters at the end. 34 = "Unknown Cnt" SLIC thinks this command was supposed to be a Cnt update, but it didn't match. 35 = "Bad Scratch" The number in the Scratch Char n command is an illegal number. 36 = "Bad Scratch Character Number" The number in the Scratch Char n command is not a legal number, contains other charcters. 37 = "No Scratch Number" The Scratch Char n command was missing the number. 38 = "Scratch Number Out of Range" The Scratch Char n commands number was out of range, 0 -255. 39 = "Bad Special" Special Init command had extra characters. 40 = "Unfinished print" SLIC thinks this is a Print command, and thinks it even knows what type, but the data parameter(s) is/are missing. 41 = "No Print Number" SLIC thinks this is a Print A command, with no accumulator number. 42 = "Bad Print Number" Number had extraneous characters. 43 = "Bad Print" Print command has % type designator but no "C" for CNT type accumulators. 44 = "Unknown If" SLIC thinks this is an If command but is unsure as to which type. 45 = "Bad If Name" The command name is missing quotes. 46 = "Bad If Number" If Ration n:1 goto "name" command has an illegal number with extraneous characters. 47 = "Bad if" The If Input = "text" goto "Name" command was missing parameters. 48 = "Bad Special Number" Special Init n had an illegal number with extraneous spaces. 49 = "Unfinished Accept" Accept command missing some piece, unsure as to which one (s). 50 = "Bad Accept Path" Accept path missing quotes. 51 = "Unknown Set command" SLIC thinks this is a set command, just unsure of which one. 52 = "No Set Time" Set Time n command is missing the number of minutes. 53 = "No Set Level" Set Level n command is missing the number of the level. 54 = "No Set Flag" Set On n or Set Off n is missing the flag number. 55 = "Bad Set Time" Set Time n minutes is out of range, 0 to 255. 56 = "Set Level Out of Range" Set Level number is out of range, 0 to 255. 57 = "Set Flag Out of Range" Set Flag number is out of range, 0 to 255.